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OAuth 2.0 for Native Apps 

Abstract 
OAuth 2.0 authorization requests from native apps should only be made 
through external user-agents, primarily the user’s browser. This 
specification details the security and usability reasons why this is 
the case and how native apps and authorization servers can implement 
this best practice. 

Status of This Memo 


This memo documents an Internet Best Current Practice. 


This document is a product of the Internet Engineering Task Force 


(IETF). It represents the consensus of the IETF community. It has 
received public review and has been approved for publication by the 
Internet Engineering Steering Group (IESG). Further information on 


BCPs is available in Section 2 of RFC 7841. 


Information about the current status of this document, any errata, 
and how to provide feedback on it may be obtained at 
https://www.rfc-editor.org/info/rfc8252. 


Copyright Notice 


Copyright (c) 2017 IETF Trust and the persons identified as the 
document authors. All rights reserved. 


This document is subject to BCP 78 and the IETF Trust’s Legal 
Provisions Relating to IETF Documents 
(https://trustee.ietf.org/license-info) in effect on the date of 
publication of this document. Please review these documents 
carefully, as they describe your rights and restrictions with respect 
to this document. Code Components extracted from this document must 
include Simplified BSD License text as described in Section 4.e of 
the Trust Legal Provisions and are provided without warranty as 
described in the Simplified BSD License. 
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1. Introduction 


Section 9 of the OAuth 2.0 authorization framework [RFC6749] 
documents two approaches for native apps to interact with the 
authorization endpoint: an embedded user-agent and an external user- 
agent. 


This best current practice requires that only external user-agents 
like the browser are used for OAuth by native apps. It documents how 
native apps can implement authorization flows using the browser as 
the preferred external user-agent as well as the requirements for 
authorization servers to support such usage. 


This practice is also known as the "AppAuth pattern", in reference to 
open-source libraries [AppAuth] that implement it. 


2. Notational Conventions 


The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", “SHALL NOT", 
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 
"OPTIONAL" in this document are to be interpreted as described in 
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 
capitals, as shown here. 


3. Terminology 


In addition to the terms defined in referenced specifications, this 
document uses the following terms: 


"native app" An app or application that is installed by the user to 
their device, as distinct from a web app that runs in the browser 
context only. Apps implemented using web-based technology but 
distributed as a native app, so-called "hybrid apps", are 
considered equivalent to native apps for the purpose of this 
specification. 


"app" A "native app" unless further specified. 


"app store" An e-commerce store where users can download and 
purchase apps. 


"OAuth" Authorization protocol specified by the OAuth 2.0 
Authorization Framework [RFC6749]. 


"external user-agent" A user-agent capable of handling the 
authorization request that is a separate entity or security domain 
to the native app making the request, such that the app Cannot 
access the cookie storage, nor inspect or modify page content. 
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"embedded user-agent" A user-agent hosted by the native app making 
the authorization request that forms a part of the app or shares 
the same security domain such that the app can access the cookie 
storage and/or inspect or modify page content. 


"browser" The default application launched by the operating system 
to handle "http" and "https" scheme URI content. 


"in-app browser tab" A programmatic instantiation of the browser 
that is displayed inside a host app but that retains the full 
security properties and authentication state of the browser. It 
has different platform-specific product names, several of which 
are detailed in Appendix B. 


"web-view" A web browser UI (user interface) component that is 
embedded in apps to render web pages under the control of the app. 


"inter-app communication" Communication between two apps on a 
device. 
"claimed "https" scheme URI" Some platforms allow apps to claim an 


"https" scheme URI after proving ownership of the domain name. 
URIs claimed in such a way are then opened in the app instead of 
the browser. 


"private-use URI scheme" As used by this document, a URI scheme 
defined by the app (following the requirements of Section 3.8 of 
[RFC7595]) and registered with the operating system. URI requests 
to such schemes launch the app that registered it to handle the 
request. 


"reverse domain name notation" A naming convention based on the 
domain name system, but one where the domain components are 
reversed, for example, "app.example.com" becomes 
"com.example.app". 


4. Overview 


For authorizing users in native apps, the best current practice is to 
perform the OAuth authorization request in an external user-agent 
(typically the browser) rather than an embedded user-agent (such as 
one implemented with web-views). 


Previously, it was common for native apps to use embedded user-agents 
(commonly implemented with web-views) for OAuth authorization 
requests. That approach has many drawbacks, including the host app 
being able to copy user credentials and cookies as well as the user 
needing to authenticate from scratch in each app. See Section 8.12 
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for a deeper analysis of the drawbacks of using embedded user-agents 
for OAuth. 


Native app authorization requests that use the browser are more 
secure and can take advantage of the user’s authentication state. 
Being able to use the existing authentication session in the browser 
enables single sign-on, as users don’t need to authenticate to the 
authorization server each time they use a new app (unless required by 
the authorization server policy). 


Supporting authorization flows between a native app and the browser 
is possible without changing the OAuth protocol itself, as the OAuth 
authorization request and response are already defined in terms of 
URIs. This encompasses URIs that can be used for inter-app 
communication. Some OAuth server implementations that assume all 
clients are confidential web clients will need to add an 
understanding of public native app clients and the types of redirect 
URIs they use to support this best practice. 


4.1. Authorization Flow for Native Apps Using the Browser 


| 
| +-------------------------- + (5) Authorization +--------------- + 
| | | Code | | 
| | Client App | ---------------------- > | Token | 
| |<---------------------- Endpoint 
a E E + | (6) Access Token, 
| | Ñ | Refresh: Token. “FoF srira ARRE + 
| | | | 
| | | | 
14) | (4) | 
Authorizat- Authoriza- 
| ion Request tion Code | 
| | | | 
| | | | 
| ov | | 
| +--------------------------- + | (2) Authorization +--------------- + 
| Request 
| BrOWSEr” 2s E >| Authorization 
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| | Code E E + 
A A EA A git? DA ay + 


Figure 1: Native App Authorization via an External User-Agent 
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Figure 1 illustrates the interaction between a native app and the 
browser to authorize the user. 


(1) Client app opens a browser tab with the authorization request. 


(2) Authorization endpoint receives the authorization request, 
authenticates the user, and obtains authorization. 
Authenticating the user may involve chaining to other 
authentication systems. 


(3) Authorization server issues an authorization code to the 
redirect URI. 


(4) Client receives the authorization code from the redirect URI. 


(5) Client app presents the authorization code at the token 
endpoint. 


(6) Token endpoint validates the authorization code and issues the 
tokens requested. 


5. Using Inter-App URI Communication for OAuth 


Just as URIs are used for OAuth 2.0 [RFC6749] on the web to initiate 
the authorization request and return the authorization response to 
the requesting website, URIs can be used by native apps to initiate 
the authorization request in the device’s browser and return the 
response to the requesting native app. 


By adopting the same methods used on the web for OAuth, benefits seen 
in the web context like the usability of a single sign-on session and 
the security of a separate authentication context are likewise gained 
in the native app context. Reusing the same approach also reduces 
the implementation complexity and increases interoperability by 
relying on standards-based web flows that are not specific toa 
particular platform. 


To conform to this best practice, native apps MUST use an external 
user-agent to perform OAuth authorization requests. This is achieved 
by opening the authorization request in the browser (detailed in 
Section 6) and using a redirect URI that will return the 
authorization response back to the native app (defined in Section 7). 
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6. 


Initiating the Authorization Request from a Native App 


Native apps needing user authorization create an authorization 
request URI with the authorization code grant type per Section 4.1 of 
OAuth 2.0 [RFC6749], using a redirect URI capable of being received 
by the native app. 


The function of the redirect URI for a native app authorization 
request is similar to that of a web-based authorization request. 
Rather than returning the authorization response to the OAuth 
client’s server, the redirect URI used by a native app returns the 
response to the app. Several options for a redirect URI that will 
return the authorization response to the native app in different 
platforms are documented in Section 7. Any redirect URI that allows 
the app to receive the URI and inspect its parameters is viable. 


Public native app clients MUST implement the Proof Key for Code 
Exchange (PKCE [RFC7636]) extension to OAuth, and authorization 
servers MUST support PKCE for such clients, for the reasons detailed 
in Section 8.1. 


After constructing the authorization request URI, the app uses 
platform-specific APIs to open the URI in an external user-agent. 
Typically, the external user-agent used is the default browser, that 
is, the application configured for handling "http" and "https" scheme 
URIs on the system; however, different browser selection criteria and 
other categories of external user-agents MAY be used. 


This best practice focuses on the browser as the RECOMMENDED external 
user-agent for native apps. An external user-agent designed 
specifically for user authorization and capable of processing 
authorization requests and responses like a browser MAY also be used. 
Other external user-agents, such as a native app provided by the 
authorization server may meet the criteria set out in this best 
practice, including using the same redirection URI properties, but 
their use is out of scope for this specification. 


Some platforms support a browser feature known as "in-app browser 
tabs", where an app can present a tab of the browser within the app 
context without switching apps, but still retain key benefits of the 
browser such as a shared authentication state and security context. 
On platforms where they are supported, it is RECOMMENDED, for 
usability reasons, that apps use in-app browser tabs for the 
authorization request. 
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7. 


7. 


Receiving the Authorization Response in a Native App 


There are several redirect URI options available to native apps for 
receiving the authorization response from the browser, the 
availability and user experience of which varies by platform. 


To fully support this best practice, authorization servers MUST offer 
at least the three redirect URI options described in the following 
subsections to native apps. Native apps MAY use whichever redirect 
option suits their needs best, taking into account platform-specific 
implementation details. 


1. Private-Use URI Scheme Redirection 


Many mobile and desktop computing platforms support inter-app 
communication via URIs by allowing apps to register private-use URI 
schemes (sometimes colloquially referred to as "custom URL schemes") 
like "com.example.app". When the browser or another app attempts to 
load a URI with a private-use URI scheme, the app that registered it 
is launched to handle the request. 


To perform an OAuth 2.0 authorization request with a private-use URI 
scheme redirect, the native app launches the browser with a standard 
authorization request, but one where the redirection URI utilizes a 
private-use URI scheme it registered with the operating system. 


When choosing a URI scheme to associate with the app, apps MUST use a 
URI scheme based on a domain name under their control, expressed in 
reverse order, as recommended by Section 3.8 of [RFC7595] for 
private-use URI schemes. 


For example, an app that controls the domain name "app.example.com" 
can use "com.example.app" as their scheme. Some authorization 
servers assign client identifiers based on domain names, for example, 
"client1234.usercontent.example.net", which can also be used as the 
domain name for the scheme when reversed in the same manner. A 
scheme such as "myapp", however, would not meet this requirement, as 
it is not based on a domain name. 


When there are multiple apps by the same publisher, care must be 
taken so that each scheme is unique within that group. On platforms 
that use app identifiers based on reverse-order domain names, those 
identifiers can be reused as the private-use URI scheme for the OAuth 
redirect to help avoid this problem. 
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Following the requirements of Section 3.2 of [RFC3986], as there is 
no naming authority for private-use URI scheme redirects, only a 
single slash ("/") appears after the scheme component. A complete 
example of a redirect URI utilizing a private-use URI scheme is: 


com.example.app:/oauth2redirect/example-provider 


When the authorization server completes the request, it redirects to 
the client's redirection URI as it would normally. As the 
redirection URI uses a private-use URI scheme, it results in the 
operating system launching the native app, passing in the URI as a 
launch parameter. Then, the native app uses normal processing for 
the authorization response. 


7.2. Claimed "https" Scheme URI Redirection 


Some operating systems allow apps to claim "https" scheme [RFC7230] 
URIs in the domains they control. When the browser encounters a 
claimed URI, instead of the page being loaded in the browser, the 
native app is launched with the URI supplied as a launch parameter. 


Such URIs can be used as redirect URIs by native apps. They are 
indistinguishable to the authorization server from a regular web- 
based client redirect URI. An example is: 


https://app.example.com/oauth2redirect/example-provider 


As the redirect URI alone is not enough to distinguish public native 
app clients from confidential web clients, it is REQUIRED in 

Section 8.4 that the client type be recorded during client 
registration to enable the server to determine the client type and 
act accordingly. 


App-claimed "https" scheme redirect URIs have some advantages 
compared to other native app redirect options in that the identity of 
the destination app is guaranteed to the authorization server by the 
operating system. For this reason, native apps SHOULD use them over 
the other options where possible. 


7.3. Loopback Interface Redirection 


Native apps that are able to open a port on the loopback network 
interface without needing special permissions (typically, those on 
desktop operating systems) can use the loopback interface to receive 
the OAuth redirect. 


Loopback redirect URIs use the "http" scheme and are constructed with 
the loopback IP literal and whatever port the client is listening on. 
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8. 


8. 


1, 


That is, "http://127.0.0.1:{port}/{path}" for IPv4, and 
"http://[::1]:{port}/{path}" for IPv6. An example redirect using the 
IPv4 loopback interface with a randomly assigned port: 


http://127.0.0.1:51004/oauth2redirect/example-provider 


An example redirect using the IPv6 loopback interface with a randomly 
assigned port: 


http://[::1]:61023/oauth2redirect/example-provider 


The authorization server MUST allow any port to be specified at the 
time of the request for loopback IP redirect URIs, to accommodate 
clients that obtain an available ephemeral port from the operating 
system at the time of the request. 


Clients SHOULD NOT assume that the device supports a particular 
version of the Internet Protocol. It is RECOMMENDED that clients 
attempt to bind to the loopback interface using both IPv4 and IPv6 
and use whichever is available. 


Security Considerations 
Protecting the Authorization Code 


The redirect URI options documented in Section 7 share the benefit 
that only a native app on the same device or the app’s own website 
can receive the authorization code, which limits the attack surface. 
However, code interception by a different native app running on the 
same device may be possible. 


A limitation of using private-use URI schemes for redirect URIs is 
that multiple apps can typically register the same scheme, which 
makes it indeterminate as to which app will receive the authorization 
code. Section 1 of PKCE [RFC7636] details how this limitation can be 
used to execute a code interception attack. 


Loopback IP-based redirect URIS may be susceptible to interception by 
other apps accessing the same loopback interface on some operating 
systems. 


App-claimed "https" scheme redirects are less susceptible to URI 
interception due to the presence of the URI authority, but the app is 
still a public client; further, the URI is sent using the operating 
system’s URI dispatch handler with unknown security properties. 
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The PKCE [RFC7636] protocol was created specifically to mitigate this 
attack. It is a proof-of-possession extension to OAuth 2.0 that 
protects the authorization code from being used if it is intercepted. 
To provide protection, this extension has the client generate a 
secret verifier; it passes a hash of this verifier in the initial 
authorization request, and must present the unhashed verifier when 
redeeming the authorization code. An app that intercepted the 
authorization code would not be in possession of this secret, 
rendering the code useless. 


Section 6 requires that both clients and servers use PKCE for public 
native app clients. Authorization servers SHOULD reject 
authorization requests from native apps that don’t use PKCE by 
returning an error message, as defined in Section 4.4.1 of PKCE 
[RFC7636]. 


8.2. OAuth Implicit Grant Authorization Flow 


The OAuth 2.0 implicit grant authorization flow (defined in 

Section 4.2 of OAuth 2.0 [RFC6749]) generally works with the practice 
of performing the authorization request in the browser and receiving 
the authorization response via URI-based inter-app communication. 
However, as the implicit flow cannot be protected by PKCE [RFC7636] 
(which is required in Section 8.1), the use of the Implicit Flow with 
native apps is NOT RECOMMENDED. 


Access tokens granted via the implicit flow also cannot be refreshed 
without user interaction, making the authorization code grant flow -- 
which can issue refresh tokens -- the more practical option for 
native app authorizations that require refreshing of access tokens. 


8.3. Loopback Redirect Considerations 
Loopback interface redirect URIs use the "http" scheme (i.e., without 
Transport Layer Security (TLS)). This is acceptable for loopback 


interface redirect URIs as the HTTP request never leaves the device. 


Clients should open the network port only when starting the 
authorization request and close it once the response is returned. 


Clients should listen on the loopback network interface only, in 
order to avoid interference by other network actors. 


While redirect URIS using localhost (i.e., 

"http://localhost: {port}/{path}") function similarly to loopback IP 
redirects described in Section 7.3, the use of localhost is NOT 
RECOMMENDED. Specifying a redirect URI with the loopback IP literal 
rather than localhost avoids inadvertently listening on network 
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interfaces other than the loopback interface. It is also less 
susceptible to client-side firewalls and misconfigured host name 
resolution on the user’s device. 


8.4. Registration of Native App Clients 


Except when using a mechanism like Dynamic Client Registration 
[RFC7591] to provision per-instance secrets, native apps are 
classified as public clients, as defined by Section 2.1 of OAuth 2.0 
[RFC6749]; they MUST be registered with the authorization server as 
such. Authorization servers MUST record the client type in the 
client registration details in order to identify and process requests 
accordingly. 


Authorization servers MUST require clients to register their complete 
redirect URI (including the path component) and reject authorization 
requests that specify a redirect URI that doesn’t exactly match the 
one that was registered; the exception is loopback redirects, where 
an exact match is required except for the port URI component. 


For private-use URI scheme-based redirects, authorization servers 
SHOULD enforce the requirement in Section 7.1 that clients use 
schemes that are reverse domain name based. At a minimum, any 
private-use URI scheme that doesn't contain a period character (".") 
SHOULD be rejected. 


In addition to the collision-resistant properties, requiring a URI 
scheme based on a domain name that is under the control of the app 
can help to prove ownership in the event of a dispute where two apps 
claim the same private-use URI scheme (where one app is acting 


maliciously). For example, if two apps claimed "com.example.app", 
the owner of "example.com" could petition the app store operator to 
remove the counterfeit app. Such a petition is harder to prove if a 


generic URI scheme was used. 


Authorization servers MAY request the inclusion of other platform- 
specific information, such as the app package or bundle name, or 
other information that may be useful for verifying the calling app’s 
identity on operating systems that support such functions. 


8.5. Client Authentication 


Secrets that are statically included as part of an app distributed to 
multiple users should not be treated as confidential secrets, as one 
user may inspect their copy and learn the shared secret. For this 
reason, and those stated in Section 5.3.1 of [RFC6819], it is NOT 
RECOMMENDED for authorization servers to require client 
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authentication of public native apps clients using a shared secret, 
as this serves little value beyond client identification which is 
already provided by the "client_id" request parameter. 


Authorization servers that still require a statically included shared 
secret for native app clients MUST treat the client as a public 
client (as defined by Section 2.1 of OAuth 2.0 [RFC6749]), and not 
accept the secret as proof of the client’s identity. Without 
additional measures, such clients are subject to client impersonation 
(see Section 8.6). 


8.6. Client Impersonation 


As stated in Section 10.2 of OAuth 2.0 [RFC6749], the authorization 
server SHOULD NOT process authorization requests automatically 
without user consent or interaction, except when the identity of the 
client can be assured. This includes the case where the user has 
previously approved an authorization request for a given client id -- 
unless the identity of the client can be proven, the request SHOULD 
be processed as if no previous request had been approved. 


Measures such as claimed "https" scheme redirects MAY be accepted by 
authorization servers as identity proof. Some operating systems may 
offer alternative platform-specific identity features that MAY be 
accepted, as appropriate. 


8.7. Fake External User-Agents 


The native app that is initiating the authorization request has a 
large degree of control over the user interface and can potentially 
present a fake external user-agent, that is, an embedded user-agent 
made to appear as an external user-agent. 


When all good actors are using external user-agents, the advantage is 
that it is possible for security experts to detect bad actors, as 
anyone faking an external user-agent is provably bad. On the other 
hand, if good and bad actors alike are using embedded user-agents, 
bad actors don’t need to fake anything, making them harder to detect. 
Once a malicious app is detected, it may be possible to use this 
knowledge to blacklist the app’s signature in malware scanning 
software, take removal action (in the case of apps distributed by app 
stores) and other steps to reduce the impact and spread of the 
malicious app. 


Authorization servers can also directly protect against fake external 
user-agents by requiring an authentication factor only available to 
true external user-agents. 
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Users who are particularly concerned about their security when using 
in-app browser tabs may also take the additional step of opening the 
request in the full browser from the in-app browser tab and complete 
the authorization there, as most implementations of the in-app 
browser tab pattern offer such functionality. 


8.8. Malicious External User-Agents 


If a malicious app is able to configure itself as the default handler 
for "https" scheme URIs in the operating system, it will be able to 
intercept authorization requests that use the default browser and 
abuse this position of trust for malicious ends such as phishing the 
user. 


This attack is not confined to OAuth; a malicious app configured in 
this way would present a general and ongoing risk to the user beyond 
OAuth usage by native apps. Many operating systems mitigate this 
issue by requiring an explicit user action to change the default 
handler for "http" and "https" scheme URIs. 


8.9. Cross-App Request Forgery Protections 


Section 5.3.5 of [RFC6819] recommends using the "state" parameter to 
link client requests and responses to prevent CSRF (Cross-Site 
Request Forgery) attacks. 


To mitigate CSRF-style attacks over inter-app URI communication 
channels (so called "cross-app request forgery"), it is similarly 
RECOMMENDED that native apps include a high-entropy secure random 
number in the "state" parameter of the authorization request and 
reject any incoming authorization responses without a state value 
that matches a pending outgoing authorization request. 


8.10. Authorization Server Mix-Up Mitigation 


To protect against a compromised or malicious authorization server 
attacking another authorization server used by the same app, it is 
REQUIRED that a unique redirect URI is used for each authorization 
server used by the app (for example, by varying the path component), 
and that authorization responses are rejected if the redirect URI 
they were received on doesn’t match the redirect URI in an outgoing 
authorization request. 


The native app MUST store the redirect URI used in the authorization 
request with the authorization session data (i.e., along with "state" 
and other related data) and MUST verify that the URI on which the 
authorization response was received exactly matches it. 
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The requirement of Section 8.4, specifically that authorization 
servers reject requests with URIs that don’t match what was 
registered, is also required to prevent such attacks. 


8.11. Non-Browser External User-Agents 


This best practice recommends a particular type of external user- 
agent: the user’s browser. Other external user-agent patterns may 
also be viable for secure and usable OAuth. This document makes no 
comment on those patterns. 


8.12. Embedded User-Agents 


Section 9 of OAuth 2.0 [RFC6749] documents two approaches for native 
apps to interact with the authorization endpoint. This best current 
practice requires that native apps MUST NOT use embedded user-agents 
to perform authorization requests and allows that authorization 
endpoints MAY take steps to detect and block authorization requests 
in embedded user-agents. The security considerations for these 
requirements are detailed herein. 


Embedded user-agents are an alternative method for authorizing native 
apps. These embedded user-agents are unsafe for use by third parties 
to the authorization server by definition, as the app that hosts the 
embedded user-agent can access the user’s full authentication 
credential, not just the OAuth authorization grant that was intended 
for the app. 


In typical web-view-based implementations of embedded user-agents, 
the host application can record every keystroke entered in the login 
form to capture usernames and passwords, automatically submit forms 
to bypass user consent, and copy session cookies and use them to 
perform authenticated actions as the user. 


Even when used by trusted apps belonging to the same party as the 
authorization server, embedded user-agents violate the principle of 
least privilege by having access to more powerful credentials than 
they need, potentially increasing the attack surface. 


Encouraging users to enter credentials in an embedded user-agent 
without the usual address bar and visible certificate validation 
features that browsers have makes it impossible for the user to know 
if they are signing in to the legitimate site; even when they are, it 
trains them that it’s OK to enter credentials without validating the 
site first. 
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Aside from the security concerns, embedded user-agents do not share 
the authentication state with other apps or the browser, requiring 
the user to log in for every authorization request, which is often 
considered an inferior user experience. 


9. IANA Considerations 
This document does not require any IANA actions. 


Section 7.1 specifies how private-use URI schemes are used for inter- 


app communication in OAuth protocol flows. This document requires in 
Section 7.1 that such schemes are based on domain names owned or 
assigned to the app, as recommended in Section 3.8 of [RFC7595]. Per 


Section 6 of [RFC7595], registration of domain-based URI schemes with 
TANA is not required. 
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Appendix A. Server Support Checklist 


OAuth servers that support native apps must: 


1. Support private-use URI scheme redirect URIs. This is required 
to support mobile operating systems. See Section 7.1. 

2. Support "https" scheme redirect URIs for use with public native 
app clients. This is used by apps on advanced mobile operating 


systems that allow app-claimed "https" scheme URIs. See 
Section 7.2. 


3. Support loopback IP redirect URIs. This is required to support 


desktop operating systems. See Section 7.3. 

4. Not assume that native app clients can keep a secret. If secrets 
are distributed to multiple installs of the same native app, they 
should not be treated as confidential. See Section 8.5. 

5. Support PKCE [RFC7636]. Required to protect authorization code 
grants sent to public clients over inter-app communication 
channels. See Section 8.1 


Appendix B. Platform-Specific Implementation Details 


This document primarily defines best practices in a generic manner, 
referencing techniques commonly available in a variety of 
environments. This non-normative section documents implementation 
details of the best practice for various operating systems. 


The implementation details herein are considered accurate at the time 
of publishing but will likely change over time. It is hoped that 
such a change won’t invalidate the generic principles in the rest of 
the document and that those principles should take precedence in the 
event of a conflict. 


B.1. iOS Implementation Details 


Apps can initiate an authorization request in the browser, without 
the user leaving the app, through the "SFSafariViewController" class 
or its successor "SFAuthenticationSession", which implement the in- 
app browser tab pattern. Safari can be used to handle requests on 
old versions of iOS without in-app browser tab functionality. 


To receive the authorization response, both private-use URI scheme 
(referred to as "custom URL scheme") redirects and claimed "https" 
scheme URIs (known as "Universal Links") are viable choices. Apps 
can claim private-use URI schemes with the "CFBundleURLTypes" key in 
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the application’s property list file, "Info.plist", and "https" 
scheme URIS using the Universal Links feature with an entitlement 
file in the app and an association file hosted on the domain. 


Claimed "https" scheme URIs are the preferred redirect choice on iOS 
9 and above due to the ownership proof that is provided by the 
operating system. 


A complete open-source sample is included in the AppAuth for iOS and 
macOS [AppAuth.iOSmacOS] library. 


B.2. Android Implementation Details 


Apps can initiate an authorization request in the browser, without 
the user leaving the app, through the Android Custom Tab feature, 
which implements the in-app browser tab pattern. The user’s default 
browser can be used to handle requests when no browser supports 
Custom Tabs. 


Android browser vendors should support the Custom Tabs protocol (by 
providing an implementation of the "CustomTabsService" class), to 
provide the in-app browser tab user-experience optimization to their 
users. Chrome is one such browser that implements Custom Tabs. 


To receive the authorization response, private-use URI schemes are 
broadly supported through Android Implicit Intents. Claimed "https" 
scheme redirect URIs through Android App Links are available on 
Android 6.0 and above. Both types of redirect URIs are registered in 
the application’s manifest. 


A complete open-source sample is included in the AppAuth for Android 
[AppAuth.Android] library. 


B.3. Windows Implementation Details 


Both traditional and Universal Windows Platform (UWP) apps can 
perform authorization requests in the user’s browser. Traditional 
apps typically use a loopback redirect to receive the authorization 
response, and listening on the loopback interface is allowed by 
default firewall rules. When creating the loopback network socket, 
apps SHOULD set the "SO_EXCLUSIVEADDRUSE" socket option to prevent 
other apps binding to the same socket. 


UWP apps can use private-use URI scheme redirects to receive the 


authorization response from the browser, which will bring the app to 
the foreground. Known on the platform as "URI Activation", the URI 
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scheme is limited to 39 characters in length, and it may include the 
"." character, making short reverse domain name based schemes (as 
required in Section 7.1) possible. 


UWP apps can alternatively use the Web Authentication Broker API in 
Single Sign-on (SSO) mode, which is an external user-agent designed 
for authorization flows. Cookies are shared between invocations of 
the broker but not the user’s preferred browser, meaning the user 
will need to log in again, even if they have an active session in 
their browser; but the session created in the broker will be 
available to subsequent apps that use the broker. Personalizations 
the user has made to their browser, such as configuring a password 
manager, may not be available in the broker. To qualify as an 
external user-agent, the broker MUST be used in SSO mode. 


To use the Web Authentication Broker in SSO mode, the redirect URI 
must be of the form "msapp://{appSID}" where "{appSID}" is the app’s 
security identifier (SID), which can be found in the app’s 
registration information or by calling the 
"GetCurrentApplicationCallbackUri" method. While Windows enforces 
the URI authority on such redirects, ensuring that only the app with 
the matching SID can receive the response on Windows, the URI scheme 
could be claimed by apps on other platforms without the same 
authority present; thus, this redirect type should be treated 
similarly to private-use URI scheme redirects for security purposes. 


An open-source sample demonstrating these patterns is available 
[SamplesForWindows]. 


B.4. macOS Implementation Details 


Apps can initiate an authorization request in the user’s default 
browser using platform APIs for opening URIs in the browser. 


To receive the authorization response, private-use URI schemes are a 
good redirect URI choice on macOS, as the user is returned right back 
to the app they launched the request from. These are registered in 
the application’s bundle information property list using the 
"CFBundleURLSchemes" key. Loopback IP redirects are another viable 
option, and listening on the loopback interface is allowed by default 
firewall rules. 


A complete open-source sample is included in the AppAuth for iOS and 
macOS [AppAuth.iOSmacOS] library. 
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B.5. Linux Implementation Details 


Opening the authorization request in the user's default browser 
requires a distro-specific command: "xdg-open" is one such tool. 


The loopback redirect is the recommended redirect choice for desktop 
apps on Linux to receive the authorization response. Apps SHOULD NOT 
set the "SO_REUSEPORT" or "SO_REUSEADDR" socket options in order to 
prevent other apps binding to the same socket. 
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